fix(server): validate push-notification URLs at config creation by SashaMIT · Pull Request #1173 · a2aproject/a2a-python

SashaMIT · 2026-08-09T14:37:41Z

Summary

The on_create_task_push_notification_config handlers (v1 and v2) stored client-supplied URLs without any validation. A caller who can create a push notification config can point the server at loopback, private-network, link-local, or cloud-metadata hosts, and the server will POST task events to that URL on every state change.

Root cause

src/a2a/server/request_handlers/default_request_handler.py and default_request_handler_v2.py call push_config_store.set_info(task_id, params, context) without checking params.url. The dispatch path (BasePushNotificationSender._dispatch_notification) is covered by #1164; this PR closes the write path.

Fix

Added push_url_validation_error to base_push_notification_sender.py (same logic as fix(server): validate push-notification URLs before dispatch (SSRF hardening) #1164: blocks non-http(s) schemes, loopback, private, link-local, multicast, reserved, and unresolvable hosts).
Called it in both on_create_task_push_notification_config handlers before storing the config.
Raises InvalidParamsError with a descriptive message on rejection.

Testing

uv run pytest tests/server/request_handlers/ -k push_notification — 55 passed.
New test: test_on_create_task_push_notification_config_rejects_invalid_url covers loopback and file: scheme rejection.
Updated existing tests that used unresolvable fixture URLs (1.example.com, callback.com) to use example.com (resolvable in CI).

Relation to #1164

#1164 validates at dispatch time (read path). This PR validates at config creation time (write path). Both are needed: write-time validation fails fast and gives the client immediate feedback; dispatch-time validation is a defense-in-depth backstop.

Made with Cursor

The on_create_task_push_notification_config handlers (v1 and v2) stored client-supplied URLs without validation. A malicious client could register a push notification config pointing at loopback, private-network, or cloud-metadata hosts, and the server would POST task events to that URL on every state change. Add push_url_validation_error checks to both create handlers, rejecting non-http(s) schemes and hosts that resolve to non-public addresses. This complements a2aproject#1164 (dispatch-time validation) by closing the write path. Test: test_on_create_task_push_notification_config_rejects_invalid_url Co-authored-by: Cursor <cursoragent@cursor.com>

- default_request_handler_v2: restore a2a.server.tasks imports under TYPE_CHECKING (patch dedented them, tripping TC001) and sort import block - base_push_notification_sender: catch OSError instead of naming socket.gaierror (check-spelling rejects the token) - cross-version client_1_0 lifecycle test uses example.com placeholder: creation now validates resolvability/public reachability, and the CRUD lifecycle never dials the URL

Upstream's own push-notification e2e tests register loopback webhooks with real local receivers, which creation-time validation rejects by design. Add allow_private_push_urls (default False) to both request handlers and opt the test harness in, matching the dispatch-path sibling's shape (a2aproject#1164). Also: str() the getaddrinfo sockaddr host for ty, ruff-format the v1 handler test.

github-actions · 2026-08-09T23:55:46Z

🧪 Code Coverage (vs `main`)

⬇️ Download Full Report

	Base	PR	Delta
src/a2a/server/request_handlers/default_request_handler.py	98.13%	98.20%	🟢 +0.07%
src/a2a/server/request_handlers/default_request_handler_v2.py	94.25%	92.89%	🔴 -1.36%
src/a2a/server/tasks/base_push_notification_sender.py	94.44%	85.71%	🔴 -8.73%
Total	93.12%	93.03%	🔴 -0.09%

Generated by coverage-comment.yml

SashaMIT · 2026-08-27T17:55:00Z

Thanks. The library default is now an injectable async push_url_validator (default push_url_validation_error, None skips). Validation runs before both set_info sites, including the send-message path. Resolver uses the running loop's getaddrinfo.

sokoliva · 2026-08-28T09:37:36Z

+        push_url_validator: Callable[[str], Awaitable[str | None]]
+        | None = push_url_validation_error,


Let's actually default to None here to avoid making a breaking change. Also this would make more sense considering the spec states should.

This also fixes the ITK error:
ERROR - Test PR - star - push notification - jsonrpc failed with exception: JSON-RPC Error: {'code': -32602, 'message': "Invalid push notification URL: host '127.0.0.1' resolves to a non-public address", 'data': [{'@type': 'type.googleapis.com/google.rpc.ErrorInfo', 'reason': 'INVALID_PARAMS', 'domain': 'a2a-protocol.org', 'metadata': {}}]}

sokoliva · 2026-08-28T09:37:57Z

+        push_url_validator: Callable[[str], Awaitable[str | None]]
+        | None = push_url_validation_error,


Same as above: default to None.

sokoliva

Thank you for making the changes. I left 2 equivalent comments. Sorry for the inconvenience and thank you for the patience!

SashaMIT requested a review from a team as a code owner August 9, 2026 14:37

SashaMIT added 2 commits August 10, 2026 06:31